home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / mann / file.n < prev    next >
Text File  |  1994-09-20  |  10KB  |  328 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/file.n,v 1.1 93/05/03 17:09:38 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS file tcl
  206. .BS
  207. '\" Note:  do not modify the .SH NAME line immediately below!
  208. .SH NAME
  209. file \- Manipulate file names and attributes
  210. .SH SYNOPSIS
  211. \fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?
  212. .BE
  213.  
  214. .SH DESCRIPTION
  215. .PP
  216. This command provides several operations on a file's name or attributes.
  217. \fIName\fR is the name of a file;
  218. if it starts with a tilde, then tilde substitution is done before
  219. executing the command (see the manual entry for \fBTcl_TildeSubst\fR
  220. for details).
  221. \fIOption\fR indicates what to do with the file name.  Any unique
  222. abbreviation for \fIoption\fR is acceptable.  The valid options are:
  223. .TP
  224. \fBfile \fBatime \fIname\fR
  225. Returns a decimal string giving the time at which file \fIname\fR
  226. was last accessed.  The time is measured in the standard POSIX
  227. fashion as seconds from a fixed starting time (often January 1, 1970).
  228. If the file doesn't exist or its access time cannot be queried then an
  229. error is generated.
  230. .TP
  231. \fBfile \fBdirname \fIname\fR
  232. Returns all of the characters in \fIname\fR up to but not including
  233. the last slash character.  If there are no slashes in \fIname\fR
  234. then returns ``.''.  If the last slash in \fIname\fR is its first
  235. character, then return ``/''.
  236. .TP
  237. \fBfile \fBexecutable \fIname\fR
  238. Returns \fB1\fR if file \fIname\fR is executable by
  239. the current user, \fB0\fR otherwise.
  240. .TP
  241. \fBfile \fBexists \fIname\fR
  242. Returns \fB1\fR if file \fIname\fR exists and the current user has
  243. search privileges for the directories leading to it, \fB0\fR otherwise.
  244. .TP
  245. \fBfile \fBextension \fIname\fR
  246. Returns all of the characters in \fIname\fR after and including the
  247. last dot in \fIname\fR.  If there is no dot in \fIname\fR then returns
  248. the empty string.
  249. .TP
  250. \fBfile \fBisdirectory \fIname\fR
  251. Returns \fB1\fR if file \fIname\fR is a directory,
  252. \fB0\fR otherwise.
  253. .TP
  254. \fBfile \fBisfile \fIname\fR
  255. Returns \fB1\fR if file \fIname\fR is a regular file,
  256. \fB0\fR otherwise.
  257. .TP
  258. \fBfile lstat \fIname varName\fR
  259. Same as \fBstat\fR option (see below) except uses the \fIlstat\fR
  260. kernel call instead of \fIstat\fR.  This means that if \fIname\fR
  261. refers to a symbolic link the information returned in \fIvarName\fR
  262. is for the link rather than the file it refers to.  On systems that
  263. don't support symbolic links this option behaves exactly the same
  264. as the \fBstat\fR option.
  265. .TP
  266. \fBfile \fBmtime \fIname\fR
  267. Returns a decimal string giving the time at which file \fIname\fR
  268. was last modified.  The time is measured in the standard POSIX
  269. fashion as seconds from a fixed starting time (often January 1, 1970).
  270. If the file doesn't exist or its modified time cannot be queried then an
  271. error is generated.
  272. .TP
  273. \fBfile \fBowned \fIname\fR
  274. Returns \fB1\fR if file \fIname\fR is owned by the current user,
  275. \fB0\fR otherwise.
  276. .TP
  277. \fBfile \fBreadable \fIname\fR
  278. Returns \fB1\fR if file \fIname\fR is readable by
  279. the current user, \fB0\fR otherwise.
  280. .TP
  281. \fBfile readlink \fIname\fR
  282. Returns the value of the symbolic link given by \fIname\fR (i.e. the
  283. name of the file it points to).  If
  284. \fIname\fR isn't a symbolic link or its value cannot be read, then
  285. an error is returned.  On systems that don't support symbolic links
  286. this option is undefined.
  287. .TP
  288. \fBfile \fBrootname \fIname\fR
  289. Returns all of the characters in \fIname\fR up to but not including
  290. the last ``.'' character in the name.  If \fIname\fR doesn't contain
  291. a dot, then returns \fIname\fR.
  292. .TP
  293. \fBfile \fBsize \fIname\fR
  294. Returns a decimal string giving the size of file \fIname\fR in bytes.
  295. If the file doesn't exist or its size cannot be queried then an
  296. error is generated.
  297. .TP
  298. \fBfile \fBstat  \fIname varName\fR
  299. Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the
  300. variable given by \fIvarName\fR to hold information returned from
  301. the kernel call.
  302. \fIVarName\fR is treated as an array variable,
  303. and the following elements of that variable are set: \fBatime\fR,
  304. \fBctime\fR, \fBdev\fR, \fBgid\fR, \fBino\fR, \fBmode\fR, \fBmtime\fR,
  305. \fBnlink\fR, \fBsize\fR, \fBtype\fR, \fBuid\fR.
  306. Each element except \fBtype\fR is a decimal string with the value of
  307. the corresponding field from the \fBstat\fR return structure; see the
  308. manual entry for \fBstat\fR for details on the meanings of the values.
  309. The \fBtype\fR element gives the type of the file in the same form
  310. returned by the command \fBfile type\fR.
  311. This command returns an empty string.
  312. .TP
  313. \fBfile \fBtail \fIname\fR
  314. Returns all of the characters in \fIname\fR after the last slash.
  315. If \fIname\fR contains no slashes then returns \fIname\fR.
  316. .TP
  317. \fBfile \fBtype \fIname\fR
  318. Returns a string giving the type of file \fIname\fR, which will be
  319. one of \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR,
  320. \fBblockSpecial\fR, \fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
  321. .TP
  322. \fBfile \fBwritable \fIname\fR
  323. Returns \fB1\fR if file \fIname\fR is writable by
  324. the current user, \fB0\fR otherwise.
  325.  
  326. .SH KEYWORDS
  327. attributes, directory, file, name, stat
  328.